PC-SIG: World of Education/PC-SiG's World of Education.iso/wor/disk0978.zip/MMAKE.DOC

Text File | 1988-05-12 | 28KB | 668 lines

                                Mmake

                      Version 1.3 User's Manual





                             MicroSystems
                             P.O. Box 471
                          Carbondale, IL  62903




REGISTRATION

This program is made available to the public as shareware.  You are free
to make and distribute an unlimited number of copies. You are to also
entitled to use the program without cost on a trial basis, to see if
it is of value to you.

If you decide to use the program, you are requested to register by
sending $20 along with your name and address to the address on the
cover of this manual.

The existence of user-supported software as an alternative to costly
commercial software depends on the good faith and cooperation of the
software's users.  Your $20 registration will enable us to continue
to upgrade this product and to develop others.   Commercial versions
of the make utility cost between $89 and $150.

Registered users are entitled to free support and to at least one
free upgrade.


FEEDBACK and SUPPORT

Registered users will be given assistance if any problems are
encountered using this program.  If you enclose a self-addressed,
stamped envelope with your questions, it will help us to answer you
more quickly.

Support is not guaranteed to non-registered users.  However, we do
appreciate feedback from all users, registered or otherwise.  If you
encounter a bug when using this program, please let us know so that
we can correct it and save others from similar aggravation.  When
reporting a problem, the more detail you can provide to us, the more
likely it is that we will be able to reproduce (and fix) the bug.
In addition to a description of the problem, it will help if you send
us copies of the files that were being processed when the problem
occured, or "dummy" files that cause the same problem.

We also welcome suggestions for improvements and added features, and
we are interested in hearing about how you have used Mmake.





WHAT MMAKE DOES

Mmake is based on the Unix "make" utility and performs the same
function, though it does not yet provide all of the sophisticated
features of the Unix utility.

Mmake is used by programmers to automate the process of compiling and
linking a program that is contained in several (or numerous) source
files.   It can be used with any language and with any compiler that
can be run from the Ms-Dos command line.  It can speed development
enormously, both by making recompilation of a program go much more
quickly, and by preventing errors when a changed file is not recompiled.

When creating or editing a complex program, it is often difficult to
remember which source files or modules have been changed and need to
be recompiled.  Mmake automates this process so that the programmer
can forget about it.  After editing files, the programmer simply
runs Mmake and the modules that have been changed will be recompiled.
Files that have not been changed are not recompiled.

Without a make utility, there are two basic strategies to compiling and
linking a program as it is being developed or when it is changed.    The
first is to simply recompile and re-link all of the source files that
make up the program, every time any of them are changed.  This has the
serious drawback of vastly increasing the amount of time spent recompiling
the program.  The other strategy is to break the program into modules
which can be compiled separately, then trying to keep track of which ones
have been changed or added.  This can be difficult, especially when an
"include" file is edited; any source files that include that "include"
file need to be recompiled, while others do not.   This puts the burden of
keeping track of which modules have been affected on the programmer, who
should be free to think about the program being written.  It also introduces
the possibility that a module that should be recompiled may not be,
thus generating errors in the program and wasting even more of the
programmer's time in debugging.

Mmake saves the time that is wasted by compiling files unnecessarily,
while preventing the errors that result when a programmer forgets to
recompile a module that has been changed.  It also frees the programmer
to think about the program being written.  When the program is ready to
be recompiled, Mmake automatically determines which source files have
been changed or affected by changes, and runs the commands necessary to
re-make the program.

Mmake does this by comparing the last modification times of the files you
are creating with the modification times of the files which are used to
create them.  Depending on which files have been changed,  Mmake runs
the appropriate programs to bring them up to date -- compilers,
assemblers, linkers, or any other executable Ms-Dos program.

We have used Mmake with 'C' compilers, the Clipper DBase compiler, the
Macro Assembler, and with programs that contained all three.  It will
work with any compiler that can be run from the Ms-Dos command line.



WHAT MMAKE DOES, continued

While Mmake is designed as a tool for programmers, it can be used in
any situation in which an action must be taken for files which have
changed and not taken for those which have not.  For example, a large
document consistng of many files could be run through a spell-checker or
text formatter, using Mmake to insure that all the files changed, and
only the files changed, were spell-checked or formatted.  Or Mmake could
compare modification times of files on a source disk and files on a backup
disk, and copy the source to the backup when the source file was the
more-recently changed.


MEMORY REQUIREMENTS

The amount of memory needed to run Mymake depends on the commands in your
make file.  Mymake.exe itself takes up about 25 K of memory while it
is running.  In addition, you must have enough memory to load and run
any command line in your make file.





HOW TO USE MMAKE

The first step in using Mmake is to create a "make file," which is
a description of the relationships among the files in the program
you are making.  The format of the make file is described in detail
below.  Once the make file is created, the process of developing a
program or modifying an existing program is greatly simplified; the
time invested in creating the make file is soon repaid.  Make files
also help to document a program, since they show all of the source
files contained in it and the relationships among them.  Of course,
as you add new source files to your program, you have to add those
files to the make file as well.

Once a make file is created, using Mmake is extremely simple.
The command line syntax is:

     Mmake /F filename /H /S /D /I

Everything after "Mmake" is optional, including the filename, which is
part of the /F option.  The options can be given in any order.  The
meaning of the command lines options are as follows:

     /F filename - Use "filename" for the make file.  If this
          option is not given, Mmake uses the default file
          name "makefile".

     /H - Help: display a list of Mymake's options.

     /S - Silent: don't display commands before running them.
          Normally, Mmake displays each command as it is run.
          This option turns off that display.  Note that the
          output of the programs themselves are not turned off,
          just Mmake's display of the command line.

     /D - Display only: display commands but don't run them.
          With this option, Mmake will show you the commands
          that would be run, based on the modification times of
          files, but it does not actually run the commands.

    /I - Ignore exit codes:  normally, Mmake will stop running if a
         compiler or other program returns with an exit code other
         than zero.  Most programs use non-zero exit codes to indicate
         an error, so this is normally desirable.  However, it you
         need to run a program that returns a non-zero exit code, the
         /I option can be used.  It tells Mmake to simply ignore the
         exit codes of the programs it runs.

For all options, a dash (-) may be used instead of the slash (e.g.,
-D or -S).



HOW TO USE MMAKE, continued

As Mmake runs, it will display the commands that it is executing (unless
the /S option is used).  If no files have been changed since the last
time they were compiled or linked, Mmake simply displays a message that
all files are up to date.  If any of the programs that Mmake runs
encounter an error, Mmake will display the error code returned by the
program, and stop.  Once you have corrected the source of the problem,
run Mmake again and it will take up where it left off, making only
those files that still need to be made.

Note that since Mmake uses the modification times of files, the date and
time must be kept current on your system (which is a good idea in any
case).   By far the most convenient way to do this is with a battery-
powered clock chip.  If you don't have such a chip in your computer,
you will have to enter the date and time before editing source files.
(Usually, this is done when booting Dos).



SETTING UP THE MAKE FILE

Mmake requires a "make file," which describes to it the files in your
program and the dependencies among them.  You can use Mmake for as
many different projects as you like, by setting up a separate make
file for each program.

The make file is a plain ascii text file; it can be created with any
text editor or word processor that will create ascii files.  You can
name the make file anything you like.  One convention is to name the
make file the same name as the program you are creating, but without
any extension.  For example, using "chess" as the name of a make file
that creates a program named "chess.exe."  If you do not give Mmake a
make file name, it will use a file named "makefile" in the default directory.

The make file consists of a number of records.  Each record starts with
a filename, which is the file to be created.  This is followed by a
colon, then a list of files upon which the file being created depends.
This "dependency line" is followed by one or more command lines, which
are the commands to be executed in order to create the file being created.

The general format of a make file record is as follows:

File to be created:  files on which it depends
    command to create the file

An example will help make this clear.  Below is a simple make file
for an imaginary chess program, followed by an explanation of its
contents.  (In the example, only three files are being created.  In
fact up to 256 files can be created by each make file):

# chess - make file for chess.exe
# dummy file used for example only
# 7/12/87

Chess.exe : Chess.obj   drawscrn.obj
    link Chess drawscrn;

Chess.Obj : Chess.c  Games.h
    cl -c Chess;

Drawscrn.obj : a:\chessboard\drawscrn.asm
    masm  a:\chessboard\drawscrn;


The first three lines of this file are comments, and have no effect on
Mmake's actions.  Comment lines can be placed anywhere in the file,
as long as the first non-space character of a comment line is "#".
Similarly,  blank lines may be inserted to improve readability;
they are ignored by Mmake.



SETTING UP THE MAKE FILE, continued

In the example make file, the first dependency line tells Mmake that
Chess.exe "depends on" each of the two .obj files listed on that line.
That is, if either of these files change, Chess.exe must be remade.
Mmake will compare the modification times of the two .Obj files with
that of chess.exe; if either of them have been changed since Chess.exe
was last created, Chess.exe will be remade.   Chess.exe will also be
created if it does not exist.

The next line of the sample make file is a command line.  It begins with a
tab character, and tells Mmake how to remake Chess.exe if it decides to
do so. This example command line tells Mmake to run the link program,
passing the names of the two .obj files to link as arguments.  Mmake
will look for the link program in the current directory, then look in the
directories specified by the Dos PATH string. This command line,
like the others in this example, is just an example; any linker or
compiler could be used -- or, for that matter, any .com or .exe file.
An exact description of what commands can be used appears below.

The next record tells Mmake that the Chess.obj file depends on two other
files, Chess.c and Games.h.  If either of these two files has a later
modification date than Chess.obj, Mmake will remake Chess.obj.  In this
example, it would run the cl compiler with the -c argument.

The drawscrn.obj record is interpreted in a similar manner.  Note that
this record contains a full path and drive specification; any
file name in any record can include a drive and/or directory specification.
If the path of a command is not given, Mmake will look in the current
directory and the directories listed in the Ms-Dos PATH    environment
string.  Files other than commands have to include thier full path
name unless they are in the current directory.

RECORD ORDER

In some commercially-available versions of the make utility, the above
make file would not work because of the order in which the files are
listed.  If, for example,  Chess.c were changed, Chess.obj would get
remade.  But Chess.exe would not, because by the time Chess.obj was
remade, the dependency line for Chess.exe would have already been checked.

This is not true of Mmake.  In the above example, before it decides
whether or not to remake Chess.exe, it will look ahead to see if any
of the files Chess.exe depends on need to be remade; if so, it will remake
those fles (looking ahead again, if necessary) before deciding whether or
not to make Chess.exe.

Therefore, the order of records in the make file is not critical.
However, Mmake will run a little faster if the records are arranged to
minimize look-ahead.  In the example, if the record for Chess.exe were
last, the make process would go faster.  Minimizing look-ahead can also
help if you encounter a "Stack Overflow" error when running Mmake; see
error messages, below.



LONG LINES

If a dependency line is too long to fit on a single 80-column line,
it can be extended by placing a backslash (\) just before the end of
the line.  Any lines ending in a backslash are considered as
continuing on the next line; for example, the lines

Chess.exe : Chess.obj   drawscrn.obj   mymove.obj   \
Scorkeep.obj  Highscr.obj  Newgame.obj  Replay.obj

are treated by Mmake as a single line.  There is no limit to the number
of lines that can be "connected" in this way.  The backslash must be
the very last character on the line.


COMMAND LINES

Each command line MUST begin with either a tab character or the '@'
character; this is how Mmake distinguishes the commands from the
dependency lines.

In the example above, only one command line is shown for each dependency
line.  However, there is no limit to the number of command lines that
can follow a dependency line, as long as each one begins with a tab
or '@' character.

A command line that begins with the '@' character must have that
character in the first column; the '@' is stripped off.  This can be
used if you are using a word processor or editor that makes it
inconvenient to use the tab character.  The '@' can be followed by
spaces for clarity.  For example, the sample make file shown above
could have been written as follows:

# chess - make file for chess.exe
# dummy file used for example only
# 7/12/87

Chess.exe : Chess.obj   drawscrn.obj
@   link Chess drawscrn;

Chess.Obj : Chess.c  Games.h
@   cl -c Chess;

Drawscrn.obj : a:\chessboard\drawscrn.asm
@   masm  a:\chessboard\drawscrn;


The characters after the '@' can be either tabs or spaces; Mmake uses
the '@' in the first column to recognize the line as a command.



COMMAND LINES, continued

Any .com or .exe file can be specified as the command to be executed.
In addition, any internal DOS command (such as cd or copy) can be
given as one of the commands, as long as it is given in the form

    command /c dir

-- that is, you must run command.com with the /c option, followed by the
Dos command you want to execute.  Batch files can be run the
same way; they cannot be run without running a copy of command.com.

Continuing the above example, instead of simply linking the .obj files
to create Chess.exe, we could also have changed directories, invoked
an editor to edit a "scores" file, changed directories back to the \Chess
directory, then run the Chess program to test it.  The following record
in the make file would accomplish this:

Chess.exe : Chess.obj   drawscrn.obj
    link Chess drawscrn ;
    command /c cd scores
    edlin   highscores
    command /c cd \Chess
    Chess

If a command being run by Mmake returns an exit code greater than zero,
Mmake will stop.  Additional commands will not be processed until you
run Mmake again.  You can override this feature by specifying the /I
option, which will cause Mmake to ignore exit codes.



ERROR MESSAGES

Mmake generates two different types of errors. Before it begins processing
files, Mmake scans the entire make file, looking for errors in the make file
itself.  Most such errors require that you edit the make file before
proceeding.   These errors are listed in alphabetical order under "MAKE
FILE ERRORS" below.

The second type of error is generated during the process of making one
of the files listed in the make file.  These errors are listed in
alphabetical order under "PROCESSING ERRORS" below.


MAKE FILE ERRORS

 /F option requires make file name.

         You entered the /F option on the Mmake command line, but
         did not follow it with the name of the make file.  If you
         want to use the defualt make file name, "makefile", you
         do not need the /F option on the command line.  If you
         want to use another file for the make file, enter /F
         followed by the name of the make file, on the command line.

 File (filename) too big (must be < 32k).

        The make file must be less than 32 K in size.  If you get
        this error, you can reduce the size of the make file by
        removing or shortening comments, or moving some files so
        that shorter path names can be used in the make file.  If your
        make file is still more than 32 K, you can get around this
        restriction by creating two separte make files and running
        Mmake on each of them.  This size limit will be removed in the
        next version of Mmake.


 Illegal file or path name: (file or path from make file)

        The displayed path or file name in the make file
        is an illegal name.  This is NOT a "file not found"
        message.  It means that a file cannot even be looked
        for because the file or path name contains
        illegal characters, two consecutive backslash ("\")
        characters, a colon in the middle of the name, or some
        other illegal combination of characters.



MAKE FILE ERRORS (continued)

 Mmake creates a temporary file named (filename).
 A file already exists with that name.
 Okay to overwrite existing file? (press y or n).

        During operation, Mmake creates a temporary file with the
        given name, in the default directory.  This file is erased
        before Mmake finishes running.  You will not see the above
        message unless a file by that name already exists in the
        default directory.  If you see this message, pressing 'N'
        will cause Mmake to stop.  Pressing 'Y' will overwrite the
        existing temporary file, destroying its contents.

 Missing colon make file line: (line from make file).

        The line displayed is a dependency line, and does not
        contain a colon separating the file to be created from
        the files upon which it depends.  Any line in the make file
        that does not begin with a tab or the '@' character is taken
        to be a dependency line unless the line right above it ends
        in a backslash, in which case it is considered part of the
        line above it.

 Missing dependencies in make file after: (line from make file).

        The dependency line displayed has a file to be created, but
        no files upon which it depends.  Each dependency line of
        the make file must contain a file to be created, then a
        colon, then one or more dependency files.

 No command line following make file line:  (line from make file).

        The dependecny line displayed is not followed by a command
        line.  Command lines must begin with a tab or '@' character.
        Each dependency line must be followed by at least one command
        line.  Some implementations of the make utility have built-in
        rules which are used when no command is given.  It is expected
        that this feature will be available in future versions of Mmake;
        this version does not provide built-in make rules.

 Not enough memory to read make file (filename)

        Mmake.exe is unable to get enough memory to read the make file.
        You need more memory in your machine to run Mmake.  If you have
        a RAM disk or "Stay Resident" utilities installed, removing them
        will make more memory available to programs such as Mmake.

        If you receive this error, we would appreciate hearing about it.



MAKE FILE ERRORS (continued)

 Too many files; make file must contain less than (number) files.

        Your make file contains more files to be created than Mmake
        can handle.  The only solution is to reduce this number of
        files in the make file; this can be done by splitting it
        into two parts and running each part separately.  If you do
        this, the order in which you run the two make files may be
        important, if the files in one depend on files in the other.

        If you receive this error, we would appreciate hearing about it.

 Two filenames before colon in make file line: (line from make file)

        The dependency line displayed has more than one file name
        before the colon.  Only one file to be created can be
        listed in each dependency line, though there can be many
        dependency files.

 Unable to open file (filename) for reading.

        The named file cannot be opened.  Normally, this means the
        file does not exist, or that it is not in the current
        directory and not in one of the directories specified by PATH.

 Unable to create temporary file (filename).

        The temporary file cannot be created.  This may mean that
        your disk is full, or that there is a directory with the
        same name as the temp file, in the default directory.  In
        the former case, remove some files to make more room on
        your disk.  Remember that Mmake can access files on more than
        one disk; just include the drive letter in the path name in
        the make file or in the Dos PATH.

 Unknown command line option: (option)

        You typed a command line option that Mmake does not
        recognize.  Type Mmake /H for a list of valid options.


PROCESSING ERRORS

 Arg list too long.

        The command line is greater than 128 bytes long.  The total
    length of the command line must be less than 128 bytes.     The
    best way to overcome this problem is to use a respone file for
    the input to your linker or compiler; most compilers and linkers
    have an option that allows this.

 Can't execute command line: (command line)
 Commands must have .exe, .com, or no extension.

        Only files ending in .com or .exe can be run as commands on
        a command line in the make file.  As explained under
        "COMMAND LINES" above, .bat files or internal Dos commands
        can be run by running a copy of command.com with its /c
        option, followed by the command you wish to run.  If a
        command in the make file has no extension, Mmake assumes
        that it has a .com or .exe extension.

 Exec format error

        The file being run is not an executable file or has been
        altered in some way which makes it impossible to run.

 Execute error: (error message)

        Mmake is unable to run the program it is attempting to
        run, for reasons explained by the error message following
        the colon.  Each of these error messages appears separately
        in this list.

 Executing: (command line)

        This is not an error message; it simply tells you what
        command or program is being executed by Mmake.  If you
        started Mmake with the /D (display only) option, this
        shows you the commands that would be executed by Mmake
        if the /D option were not used.

 Exit code: (number)

        The program just run by Mmake ended with an error code;
        the exit code printed is from that program.  Consult the
        manual for the program creating the error to find out what
        the error code means.  Mmake will stop executing after
        such an error is returned unless the /I option is used.

 No such file or directory.

        The command you specified cannot be found.



PROCESSING ERRORS (continued)

 Not enough core.

        There is not enough memory to run the program that Mmake
        is attempting to run.  If you can free some memory by
        removing "Terminate but Stay Resident" utilities, RAM
        disks, print spoolers, etc., Mmake may be able to run
        the program.

 Stack overflow.

         Mmake has run out of stack space during execution.  The
         most common cause of this is a dependency line that
         has a file dependent on itself, such as

         Chess.obj : Chess.obj.

         The solution is to fix the dependency line.

         This error may also be caused by a deeply-nested set of
         dependencies.   In this case, you should be able to overcome
         the problem by rearranging the make file to minimize
         look-ahead, since look-ahead uses stack space.  See the
         section above on "RECORD ORDER" for an explanation of how to
         minimize look-ahead.

         If you receive this error, we would appreciate hearing
         about it.

 Unable to find or make (filename).

        The named file is listed in the make file as one upon which
        another file depends.  However, the named file does not
        exist, and there is no record in the make file indicating
        how it can be created.  This causes Mmake to stop.  This
        usually means that either the file name was incorrectly
        typed,  that a record needs to be added to the make file
        indicating how the named file is to be made, or that the
        file is in a different directory than the one listed in the
        make file.

 Unable to make file (filename); no commands.

        There are no commands following the dependency line for
        the named file.  If you get this error, we would appreciate
        hearing about it.

 Warning:  Command line contains more than (number) arguments. Extra ignored.

        The number shown is the maximum number of arguments that can be
        passed to a program run by Mmake.  The command is still run,
        but only the first (number) arguments have been passed.

        If you get this error, we would appreciate hearing about it.